Quick Start: Multiple Images Per Variant

🎯 Goal

Show 4-6 different images for each product variant (instead of just one). Perfect for Hat Lab functionality.

✅ Simple 3-Step Process

Step 1: Enable the Setting

1. Go to Theme Customizer
2. Select your product template
3. Click Product Media Gallery block
4. Turn on "Hide unselected variant media"
5. (Optional) Turn on "Hide untagged images (strict mode)" to hide all untagged images
6. Save

Step 2: Tag Your Images

For each product image in Shopify Admin:

1. Click the image → Edit
2. In Alt text, add: variant-{color}-{size}
3. Click Done

Example for a Red Small variant:

Alt text: Red t-shirt on model variant-red-small

Example for a Blue Large variant:

Alt text: Blue t-shirt on model variant-blue-large

Step 3: That's It!

When customers select variants, only the tagged images will appear.

📝 Quick Rules

• Lowercase with hyphens: variant-red-small (not variant-Red-Small)
• Match option order: If Color is first option, then Size, use variant-red-small (not variant-small-red)
• Multiple images OK: Tag as many images as you want per variant
• No tag = shows always: Leave alt text without variant- tag to show image for all variants

💡 Pro Tips

For products with 2 options (Color + Size):

variant-red-small
variant-red-medium
variant-blue-large

For products with 1 option (Color only):

variant-red
variant-blue

For products with 3 options (Color + Size + Material):

variant-red-small-cotton
variant-blue-large-polyester

🔧 Common Issues

Problem: Images aren't hiding

• ✅ Check setting is enabled
• ✅ Check spelling in variant tags
• ✅ Make sure tags are lowercase with hyphens

Problem: Wrong images showing

• ✅ Verify option order matches Shopify
• ✅ Check for typos in tags

📖 Need More Help?

See Variant Image Tagging for detailed documentation.